rbibutils/ 0000755 0001762 0000144 00000000000 14516216412 012253 5 ustar ligges users rbibutils/NAMESPACE 0000644 0001762 0000144 00000001117 14055130134 013464 0 ustar ligges users useDynLib(rbibutils, .registration=TRUE, .fixes = "C_")
importFrom("utils", "person", "bibentry", "toBibtex")
importFrom(tools, file_ext, toRd, bibstyle, getBibstyle)
## import(xml2)
## exportPattern("^[[:alpha:]]+")
S3method(print, bibentryExtra)
S3method(format, bibentryExtra)
S3method("[", bibentryExtra)
S3method("[[", bibentryExtra)
S3method("$<-", bibentryExtra)
S3method("[[<-", bibentryExtra)
S3method("toRd", bibentryExtra)
export(
bibConvert,
readBib,
writeBib,
readBibentry,
writeBibentry,
charToBib,
rbibutils_formats,
register_JSSextra
)
rbibutils/README.md 0000644 0001762 0000144 00000013077 14153746243 013551 0 ustar ligges users [](https://cran.r-project.org/package=rbibutils)
[](https://www.r-pkg.org/pkg/rbibutils)
[](https://r-pkg.org/pkg/rbibutils)
[](https://github.com/GeoBosh/rbibutils/actions)
[](https://app.codecov.io/gh/GeoBosh/rbibutils)
Read and write 'BibTeX' files. Convert bibliography files between various
formats, including BibTeX, BibLaTeX, PubMed, EndNote and Bibentry. Includes an R
port of the `bibutils` utilities.
# Installing rbibutils
Install the [latest stable version](https://cran.r-project.org/package=rbibutils) from CRAN:
install.packages("rbibutils")
You can also install the [development version](https://github.com/GeoBosh/rbibutils) of `rbibutils` from Github:
library(devtools)
install_github("GeoBosh/rbibutils")
# Overview
Import and export 'BibTeX' files. Convert bibliography files between various
formats. All formats supported by the `bibutils` utilities are available, see
`bibConvert()` for a complete list. In addition, conversion from and to
`bibentry`, the R native representation based on Bibtex, is supported.
`readBib()` and `writeBib()` import/export BiBTeX files. `readBibentry()` and
`writeBibentry()` import/export `R` source files in which the references are
represented by `bibentry()` calls.
The convenience function `charToBib()` takes input from a character vector,
rather than a file. It calls `readBib()` or `bibConvert()`.
`bibConvert()` takes an input bibliography file in one of the supported formats,
converts its contents to another format, and writes the result to a file. All
formats, except for `rds` (see below) are plain text files. `bibConvert()` tries
to infer the input/output formats from the file extentions. There is ambiguity
however about `bib` files, which can be either Bibtex or Biblatex. Bibtex is
assumed if the format is not specified. Also, the `xml` extension is shared by
XML-based formats. Its default is 'XML MODS intermediate' format.
The default encoding is UTF-8 for both, input and output. All encodings handled
by `bibutils` are supported. Besides UTF-8, these include `gb18030` (Chinese),
ISO encodings such as `iso8859_1`, Windows code pages (e.g. `cp1251` for Windows
Cyrillic) and many others. Common alternative names are also accepted
(e.g. `latin1`).
Bibentry objects can be input from an `R` source file or from an `rds` file. The
`rds` file should contain a `bibentry` R object, saved from R with `saveRDS()`.
The `rds` format is a compressed binary format`. Alternatively, an R source file
containing one or more bibentry instructions and maybe other commands can be
used. The R file is sourced and all bibentry objects created by it are
collected.
# Examples:
## readBib
The examples in this section import the following file:
bibacc <- system.file("bib/latin1accents_utf8.bib", package = "rbibutils")
Note that some characters may not be displayed on some locales. Also, on Windows
some characters may be "approximated" by other characters.
Import the above bibtex file into a `bibentry` object. By default TeX escape
sequences representing characters are kept as is:
be0 <- readBib(bibacc)
be0
print(be0, style = "bibtex")
As above, using the direct option:
be1 <- readBib(bibacc, direct = TRUE)
## readBib(bibacc, direct = TRUE, texChars = "keep") # same
be1
print(be1, style = "bibtex")
Use the `"convert"` option to convert TeX sequences to true characters:
be2 <- readBib(bibacc, direct = TRUE, texChars = "convert")
be2
print(be2, style = "R")
(On Windows the Greek characters alpha and delta may be printed as 'a' and 'd'
but internally they are alpha and delta.)
Use the `"export"` option to convert other characters to ASCII TeX sequences,
when possible (currently this option doesn't handle well mathematical
expressions):
be3 <- readBib(bibacc, direct = TRUE, texChars = "export")
print(be3, style = "bibtex")
## bibConvert
Convert Bibtex file `myfile.bib` to a `bibentry` object and save the latter to
`"myfile.rds":
bibConvert("myfile.bib", "myfile.rds", informat = "bibtex", outformat = "bibentry")
bibConvert("myfile.bib", "myfile.rds")
Convert Bibtex file `myfile.bib` to a Biblatex save to `"biblatex.bib":
bibConvert("myfile.bib", "biblatex.bib", "bibtex", "biblatex")
bibConvert("myfile.bib", "biblatex.bib", outfile = "biblatex")
Convert Bibtex file `myfile.bib` to Bibentry and save as `rds` or `R`:
bibConvert("myfile.bib", "myfile.rds")
bibConvert("myfile.bib", "myfile.R")
Read back the above files and/or convert them to other formats:
readLines("myfile.R")
file.show("myfile.R")
readRDS("myfile.rds")
bibConvert("myfile.rds", "myfile.bib")
bibConvert("myfile.R", "myfile.bib")
Assuming `myfile.bib` is a Biblatex file, convert it to Bibtex and save to `bibtex.bib`:
bibConvert("myfile.bib", "bibtex.bib", "biblatex", "bibtex")
bibConvert("myfile.bib", "bibtex.bib", "biblatex")
Assuming "myfile.med" is a PubMed file, convert it to Bibtex:
bibConvert(infile = "myfile.med", outfile = "bibtex.bib", informat = "med", outformat = "bib")
bibConvert(infile = "myfile.med", outfile = "bibtex.bib", informat = "med") # same
See `bibConvert()` for further examples and their results.
rbibutils/man/ 0000755 0001762 0000144 00000000000 14333413045 013024 5 ustar ligges users rbibutils/man/register_JSSextra.Rd 0000644 0001762 0000144 00000005742 14053236437 016741 0 ustar ligges users \name{register_JSSextra}
\alias{register_JSSextra}
\title{Create and register bibstyle JSSextra}
\description{Create and register bibstyle JSSextra.}
\usage{
register_JSSextra(make_default = FALSE, reset = FALSE, parent_style = "JSS")
}
\arguments{
\item{make_default}{
if \code{TRUE} make \code{"JSSextra"} default.
}
\item{reset}{
recreate bibstyle \code{"JSSextra"}.
}
\item{parent_style}{
the style from which to derive \code{"JSSextra"}.
}
}
\details{
\code{register_JSSextra} creates \code{"JSSextra"} and registers it
for use in the current \R session. This means that it can be specified
for functions which accept a bibstyle argument, most notably printing
objects from class \code{"bibentry"} and \code{"bibentryExtra"}.
In normal use \code{register_JSSextra} is called once in a
session.
Functions accepting a bibstyle argument use a default style if such an
argument is not provided. In most cases it is \code{"JSS"}.
The default style can be changed at any time to any of the styles
currently registered in the session using
\code{tools::bibstyle()}. A list of these styles can be obtained
with \code{tools::getBibstyle(TRUE)}. The currently default style can
be seen with \code{tools::getBibstyle()}.
As a convenience \code{register_JSSextra(TRUE)} makes and registers
\code{"JSSextra"} as the default style.
The remaining arguments should rarely be needed in normal
circumstances.
\code{register_JSSextra} stores the bibstyle object it creates and
just uses it when called again. \code{reset = TRUE} can be used to
force a fresh copy of \code{"JSSextra"} to be created.
By default \code{"JSSextra"} is derived from \code{"JSS"}. To base it
on a different style, use argument \code{parent_style}.
}
\value{
\code{register_JSSextra} is used mainly for the side effect of
registering and setting the style as default. It returns the created
style (an environment) but it can be discarded.
}
%\references{
%%% ~put references to the literature/web site here ~
%}
\author{Georgi N. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
## current default style
tools::getBibstyle()
tools::getBibstyle(TRUE) # all styles, currently "JSS" only
register_JSSextra() # register "JSSextra"
tools::getBibstyle(TRUE) # now it is available
tools::getBibstyle() # ... but not default
register_JSSextra(TRUE) # this makes it default
tools::getBibstyle()
## setting default style with bibstyle():
tools::bibstyle("JSS", .default = TRUE)
tools::getBibstyle()
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory (show via RShowDoc("KEYWORDS")):
\keyword{documentation}
% \keyword{ ~kwd2 }
% Use only one keyword per line.
% For non-standard keywords, use \concept instead of \keyword:
% \concept{ ~cpt1 }
% \concept{ ~cpt2 }
% Use only one concept per line.
rbibutils/man/bibConvert.Rd 0000644 0001762 0000144 00000030117 14333416524 015417 0 ustar ligges users \name{bibConvert}
\alias{bibConvert}
\title{Convert between bibliography formats}
\description{
Read a bibliography file in one of the supported formats, convert it
to nnother format, and write it to a file.
}
\usage{
bibConvert(infile, outfile, informat, outformat, \dots, tex, encoding,
options)
}
\arguments{
\item{infile}{input file, a character string.}
\item{outfile}{output file, a character string.}
\item{informat}{
input format, a character string, see sections \dQuote{Supported
formats} and \dQuote{Details}.
}
\item{outformat}{
output format, a character string, see sections \dQuote{Supported
formats} and \dQuote{Details}.
}
\item{...}{not used.}
\item{tex}{TeX specific options, see Details, a character vector.}
\item{encoding}{
\code{character(2)}, a length two vector specifying input and output
encodings. Default to both is \code{"utf8"}, see Details.
}
\item{options}{
mainly for debugging: additional options for the converters, see
Details.
}
}
\details{
Arguments \code{informat} and \code{outformat} can usually be omitted,
since \code{bibConvert} infers them from the extensions of the names
of the input and output files, see section "File extensions" below.
However, there is ambiguity for the extension \code{"bib"}, since it
is used for Bibtex and BibLaTeX entries. For this extension, the
default for both, \code{informat} and \code{outformat}, is
\code{"bibtex"}.
Package \pkg{rbibutils} supports format \code{"bibentry"}, in addition
to the formats supported by the bibutils library. A \code{bibentry}
object contains one or more references. Two formats are supported for
\code{"bibentry"} for both input and output. A bibentry object
previously saved to a file using \code{saveRDS} (default extension
\code{"rds"}) or an R source file containing one or more
\code{bibentry} commands. The \code{"rds"} file is just read in and
should contain a \code{bibentry} object.
When \code{bibconvert} outputs to an R source file, two variants are
supported: \code{"R"} and \code{"Rstyle"}. When (\code{outformat =
"R"}, there is one \code{bibentry} call for each reference, just as in
a Bibtex file, each reference is a single entry. \code{outformat =
"Rstyle"} uses the format of \code{print(be, style = "R")}, i.e., the
\code{bibentry} calls are output as a comma separated sequence wrapped
in \code{c()}. For input, it is not necessary to specify which
variant is used.
% Such a file can be used as input to \code{bibConvert} (\code{informat
% = "R"}). For input \code{bibConvert} accepts also R code containing
% additional instructions. The input file is (effectively)
% \code{source}'d, all bibentry objects created by it are collected and
% merged into a single \code{bibentry} object.
Note that when the input format and output formats are identical, the
conversion is not necessarilly a null operation (except for
\verb{xml}, and even that may change). For example, depending on the
arguments the character encoding may change. Also, input BibTeX files
may contain additional instructions, such as journal abbreviations,
which are expanded and incorporated in the references but not
exported. It should be remembered also that there may be loss of
information when converting from one format to another.
For a complete list of supported bibliography formats, see section
\dQuote{Supported formats} below. The documentation of the original
bibutils library (Putnam 2020) gives further details.
Argument \code{encoding} is a character vector containing 2 elements,
specifying the encoding of the input and output files. If the
encodings are the same, a length one vector can be supplied. The
default encodings are UTF-8 for input and output. A large number of
familiar encodings are supported, e.g. \code{"latin1"} and
\code{"cp1251"} (Windows Cyrillic). Some encodings have two or more
aliases and they are also accepted. If an unknown encoding is
requested, a list of all supported encodings will be printed.
Argument \code{tex} is an unnamed character vector containing switches
for bibtex input and output (mostly output). Currently, the following
are available:
\describe{
\item{uppercase}{write bibtex tags/types in upper case.}
\item{no_latex}{
do not convert latex-style character combinations to letters.
}
\item{brackets}{use brackets, not quotation marks surrounding data.}
\item{dash}{
use one dash \code{"-"}, not two \code{"--"}, in page ranges.
}
\item{fc}{add final comma to bibtex output.}
}
By default latex encodings for accented characters are converted to
letters. This may be a problem if the output encoding is not UTF-8,
since some characters created by this process may be invalid in that
encoding. For example, a BibTeX file which otherwise contains only
cyriilic and latin characters may have a few entries with authors
containing latin accented characters represented using the TeX
convention. If those characters are not converted to Unicode letters,
they can be exported to \code{"cp1251"} (Windows Cyrillic) for
example. Specifying the option \code{no_latex} should solve the
problem in such cases.
Argument \code{options} is mostly for debugging and mimics the command
line options of the bibutils' binaries. The argument is a named
character vector and is supplied as \code{c(tag1= val1, tag2 = val2,
...)}, where each tag is the name of an option and the value is the
corresponding value. The value for options that do not require one is
ignored and can be set to \code{""}. Some of the available options
are:
\describe{
\item{h}{help, show all available options.}
\item{nb}{do not write Byte Order Mark in UTF8 output.}
\item{verbose}{print intermediate output.}
\item{debug}{print even more intermediate output.}
}
}
\section{Supported formats}{
If an input or output format is not specified by arguments, it is
inferred, if possible, from the file extension.
In the table below column Abbreviation shows the abbreviation for
arguments \code{informat} and \code{outformat}, column FileExt gives
the default file extension for that format, column Input (Output)
contains TRUE if the format is supported for input (output) and FALSE
otherwise. Column Description gives basic description of the format.
% \tabular{ll}{%
% ads \tab ADS reference format \cr
% bib \tab BibTeX \cr
% bibtex \tab BibTeX \cr
% biblatex \tab BibLaTeX \cr
% copac \tab COPAC format references \cr
% ebi \cr
% end \tab EndNote (Refer format) \cr
% endx \tab EndNote XML \cr
% isi \tab ISI web of science \cr
% med \tab Pubmed XML references \cr
% nbib \tab Pubmed/National Library of Medicine nbib format \cr
% ris \tab RIS format \cr
% R \tab R source file containing \code{bibentry} commands \cr
% r \tab R source file containing \code{bibentry} commands \cr
% Rstyle \tab R source file containing \code{bibentry} commands \cr
% rds \tab bibentry object in a binary file created by \code{saveRDS()} \cr
% xml \tab MODS XML intermediate \cr
% wordbib \tab Word 2007 bibliography format
% }
\Sexpr[stage=build,results=rd]{paste("\\\\tabular{lllll}{", paste0(paste("\\\\strong{", colnames(rbibutils::rbibutils_formats), "}", collapse = " \\\\tab ")), "\\\\cr ", paste(rbibutils::rbibutils_formats[ , 1], rbibutils::rbibutils_formats[ , 2], rbibutils::rbibutils_formats[ , 3], rbibutils::rbibutils_formats[ , 4], rbibutils::rbibutils_formats[ , 5], sep = " \\\\tab ", collapse = "\\\\cr "), "\n}")}
The file \code{"easyPubMedvig.xml"} used in the examples for Pubmed
XML (\code{"med"}) was obtained using code from the vignette in
package \pkg{easyPubMed} (Fantini 2019).
}
\value{
The function is used for the side effect of creating a file in the
requested format. It returns a list, currently containing the
following components:
\item{infile}{name of the input file,}
\item{outfile}{name of the output file,}
\item{nref_in}{number of references read from the input file,}
\item{nref_out}{number of references written to the output file.}
Normally, \code{nref_in} and \code{nref_out} are the same. If some
references were imported successfully but failed on export,
\code{nref_out} may be smaller than \code{nref_in}. In such cases
informative messages are printed during processing. (If this happens
silently, it is probably a bug and please create an issue on Github.)
}
\author{Georgi N. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\references{
% bibentry: Rpackage:easyPubMed
Damiano Fantini (2019).
\dQuote{easyPubMed: Search and Retrieve Scientific Publication Records from PubMed.}
R package version 2.13, \url{https://CRAN.R-project.org/package=easyPubMed}.
% end:bibentry: Rpackage:easyPubMed
% bibentry: bibutils6.10
Chris Putnam (2020).
\dQuote{Library bibutils, version 6.10.}
\url{https://sourceforge.net/projects/bibutils/}.
% end:bibentry: bibutils6.10
}
%\seealso{
%%% ~~objects to See Also as \code{\link{help}}, ~~~
%}
\examples{
fn_biblatex <- system.file("bib", "ex0.biblatex", package = "rbibutils")
fn_biblatex
## file.show(fn_biblatex)
## convert a biblatex file to xml
modl <- tempfile(fileext = ".xml")
bibConvert(infile = fn_biblatex, outfile = modl, informat = "biblatex", outformat = "xml")
## file.show(modl)
## convert a biblatex file to bibtex
bib <- tempfile(fileext = ".bib")
bib2 <- tempfile(fileext = ".bib")
bibConvert(infile = fn_biblatex, outfile = bib, informat = "biblatex", outformat = "bib")
## file.show(bib)
## convert a biblatex file to bibentry
rds <- tempfile(fileext = ".rds")
fn_biblatex
rds
be <- bibConvert(fn_biblatex, rds, "biblatex", "bibentry")
bea <- bibConvert(fn_biblatex, rds, "biblatex") # same
readRDS(rds)
## convert to R source file
r <- tempfile(fileext = ".R")
bibConvert(fn_biblatex, r, "biblatex")
## file.show(r)
cat(readLines(r), sep = "\n")
fn_cyr_utf8 <- system.file("bib", "cyr_utf8.bib", package = "rbibutils")
## Can't have files with different encodings in the package, so below
## first convert a UTF-8 file to something else.
##
## input here contains cyrillic (UTF-8) output to Windows Cyrillic,
## notice the "no_latex" option
a <- bibConvert(fn_cyr_utf8, bib, encoding = c("utf8", "cp1251"), tex = "no_latex")
## now take the bib file and convert it to UTF-8
bibConvert(bib, bib2, encoding = c("cp1251", "utf8"))
\donttest{
## Latin-1 example: Author and Title fileds contain Latin-1 accented
## characters, not real names. As above, the file is in UTF-8
fn_latin1_utf8 <- system.file("bib", "latin1accents_utf8.bib", package = "rbibutils")
## convert to Latin-1, by default the accents are converted to TeX combinations:
b <- bibConvert(fn_latin1_utf8, bib , encoding = c("utf8", "latin1"))
cat(readLines(bib), sep = "\n")
## use "no_latex" option to keep them Latin1:
c <- bibConvert(fn_latin1_utf8, bib , encoding = c("utf8", "latin1"), tex = "no_latex")
## this will show properly in Latin-1 locale (or suitable text editor):
##cat(readLines(bib), sep = "\n")
## gb18030 example (Chinese)
##
## prepare some filenames for the examples below:
xeCJK_utf8 <- system.file("bib/xeCJK_utf8.bib", package = "rbibutils")
xeCJK_gb18030 <- system.file("bib/xeCJK_gb18030.bib", package = "rbibutils")
fn_gb18030 <- tempfile(fileext = ".bib")
fn_rds <- tempfile(fileext = ".rds")
## input bib file utf8, output bib file gb18030:
bibConvert(xeCJK_utf8, fn_gb18030, encoding = c("utf8", "gb18030"))
## input bib file utf8, output file rds (and the rds object is returned
bibConvert(xeCJK_utf8, fn_rds)
unlink(fn_gb18030)
unlink(fn_rds)
## a Pubmed file
fn_med <- system.file("bib/easyPubMedvig.xml", package = "rbibutils")
## convert a Pubmed file to bibtex:
bibConvert(fn_med, bib, informat = "med")
## convert a Pubmed file to rds and import:
#bibConvert(fn_med, rds, informat = "med")
}
unlink(c(modl, bib, bib2, r, rds))
}
\keyword{documentation}
% use one of RShowDoc("KEYWORDS")
rbibutils/man/readBib.Rd 0000644 0001762 0000144 00000022735 14160045216 014653 0 ustar ligges users \name{readBib}
\alias{readBib}
\alias{writeBib}
\alias{charToBib}
\title{Read and write bibtex files}
\description{Read and write bibtex files.}
\usage{
readBib(file, encoding = NULL, \dots, direct = FALSE,
texChars = c("keep", "convert", "export", "Rdpack"),
macros = NULL, extra = FALSE, key, fbibentry = NULL)
writeBib(object, con = stdout(), append = FALSE)
charToBib(text, informat, \dots)
}
\arguments{
\item{file}{name or path to the file, a character string.}
\item{encoding}{the encoding of \code{file}, a character string.}
\item{direct}{
If \code{TRUE} parse 'file' directly to \code{bibentry}, otherwise
convert first to intermediate XML, then to \code{bibentry}.
}
\item{texChars}{
What to do with characters represented by TeX commands (for
example, accented Latin charaters? If \code{"export"},
export as TeX escapes when possible. If \code{"convert"}, convert
to the target encoding. If \code{"keep"}, output the characters as
they were in the input file, like \code{"export"}, but don't convert
normal characters to TeX escapes.
\code{"Rdpack"} is mainly for internal use and its actions may be
changed. It is equivalent to "keep" plus some additional processing,
see \url{https://github.com/GeoBosh/rbibutils/issues/7#issue-1020385889}.
}
\item{macros}{
additional bib files, usually containing bibtex macros, such as
journal abbreviations.
}
\item{object}{a \code{bibentry} object.}
\item{con}{filename (a character string) or a text connection}
\item{append}{if \code{TRUE} append to the file.}
\item{text}{
a character vector.
}
\item{informat}{
the input format, defaults to \code{"bibtex"}.
}
\item{key}{
a character vectors of key(s) to use for entries without cite keys.
Should have the same number of elements as the number of such entries.
}
\item{...}{
for \code{charTobib}, arguments to be passed on to \code{readBib} or
\code{bibConvert}, see Details.
Not used by \code{readBib} and \code{writeBib} (which throw error to
avoid silently ignoring unknown arguments).
}
\item{extra}{if \code{TRUE}, allow non-standard bibtex types.}
\item{fbibentry}{a function to use for generating bib objects instead
of \code{bibentry()}, see Details.}
}
\details{
\code{readBib} is wrapper around \code{bibConvert} for import of
bibtex files into bibentry objects.
If \code{direct = FALSE}, the bibtex file is converted first to XML
intermediate, then the XML file is converted to bibentry. The
advantage of this is that it gives a standardised representation of
the bibtex input. Fields that cannot be mapped to the intermediate
format are generally omitted.
If \code{direct = TRUE} the input file is converted directly to
bibentry, without the XML intermediate step. This means that
non-standard fields in the bib entries are preserved in the bibentry
object.
Argument \code{texChars}, currently implemented only for the case
\code{direct = TRUE}, gives some control over the processing of TeX
sequences representing characters (such as accented Latin characters):
If it is \code{"keep"} (the default), such sequences are kept as in
the input. \code{"convert"} causes them to be converted to the
characters they represent. Finally, \code{"export"} exports characters
as TeX sequences, whenever possible.
The difference between \code{"keep"} and \code{"export"} is that
\code{"keep"} does not convert normal characters to TeX escapes, while
\code{"export"} does it if possible. For example, if the input file
contains the TeX sequence \verb{\\"o}
representing the letter o-umlaut, \code{"keep"} and \code{"export"}
will keep it as TeX sequence, while \code{"convert"} will convert it
to the character o-umlaut in the output encoding (normally UTF-8). On
the othe hand, if the input file contains the character o-umlaut, then
\code{"keep"} and \code{"convert"} will convert it to the output
encoding of o-umlaut, while \code{"export"} will export it as
\verb{\\"o}.
% 2021-10-21 commenting out since it is fixed now.
%
% Note that \code{"convert"} converts also a large number of
% mathematical symbols (such as \code{"\\alpha"}) to the target encoding
% (UTF-8), which may or may not be desirable. Also, some mathematical
% formulas may cause surprises.
Currently, \code{texChars = "export"} does not process properly
mathematical formulas.
\code{fbibentry}, if supplied, should be a function with arguments
like bibentry to be used instead of \code{utils::bibentry} for
creating bib objects in \R.
\code{writeBib} writes a \code{bibentry} object to a bibtex file.
\code{charTobib} is a convenience function for reading or converting
bibliography information, accepting the input from a
character vector rather than a file. If \code{informat} is missing it calls
\code{readBib}, otherwise \code{bibConvert}. In both cases
the remaining arguments are passed on and should be suitable for the
called function.
The files specified by argument \code{macros} are read in before those
in \code{file}. Currently this is implemented by concatenating the
files in the order they appear in \code{c(macros, file)}. It is ok for
\code{macros} to be \code{character(0)}.
}
\value{
for \code{readBib}, a \code{bibentry} object. If \code{extra} is
\code{TRUE} it can also be \code{bibentryExtra} (which inherits from
\code{bibentry}). If \code{fbibentry} is a function the return value
is whatever it returns.
for \code{writeBib}, the \code{bibentry} object (invisibly)
}
% \references{
% %% ~put references to the literature/web site here ~
% }
\author{Georgi N. Boshnakov}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
\code{\link{readBibentry}} and \code{\link{writeBibentry}} for
import/export to R code.
\code{\link{bibConvert}}
}
\examples{
## create a bibentry object
bibs <- readBib(system.file("REFERENCES.bib", package = "rbibutils"),
encoding = "UTF-8")
## write bibs to a file
fn <- tempfile(fileext = ".bib")
writeBib(bibs, fn)
## see the contents of the file
readLines(fn) # or: file.show(fn)
## import a bib file containing Chineese characters encoded with UTF-8:
ch_bib <- readBib(system.file("bib/xeCJK_utf8.bib", package = "rbibutils"))
ch_bib
print(ch_bib, style = "R")
## import a bib file encoded with the official Chineese encoding:
ch_bib2 <- readBib(system.file("bib/xeCJK_gb18030.bib", package = "rbibutils"),
encoding = "gb18030")
## a dummy reference with accented characters
## (in the file some are uft8, others are TeX escapes)
bibacc <- system.file("bib/latin1accents_utf8.bib", package = "rbibutils")
## export as UTF-8 characters
## this will print as true characters in suitable locale:
be <- readBib(bibacc, direct = TRUE, texChars = "convert")
print(be, style = "R")
print(be, style = "bibtex")
## compare to the input file:
readLines(bibacc)
be1 <- readBib(bibacc, direct = TRUE)
be1a <- readBib(bibacc, direct = TRUE, texChars = "keep") # same
be1
print(be1, style = "R")
print(be1, style = "bibtex")
## export as TeX escapes, when possible
be2 <- readBib(bibacc, direct = TRUE, texChars = "export") ## same
be2
print(be2, style = "R")
print(be2, style = "bibtex")
## in older versions (up to 2.2.4) of rbibutils, "convert" converted
## a lot of TeX commands representing symbols to characters.
## This is no longer the case:
be3 <- readBib(bibacc, direct = TRUE, texChars = "convert")
## be3
print(be3, style = "R")
## print(be3, style = "bibtex")
## charToBib
##
## get a bibtex reference for R
Rcore <- format(citation(), style = "bibtex")
## add a citation key
Rcore <- sub("@Manual{", "@Manual{Rcore", Rcore, fixed = TRUE)
cat(Rcore, sep = "\n")
beRcore <- charToBib(Rcore)
beRcore
class(beRcore)
print(beRcore, style = "R")
## bibtex entries generated by citation() don't have cite keys.
## this sets the key to 'Rcore'
beRcore <- charToBib(toBibtex(citation()), key = "Rcore")
beRcore$key == "Rcore" # TRUE
## this sets two keys
bemore <- charToBib(toBibtex( c(citation(), citation("rbibutils"))),
key = c("Rcore", "Rpackage:rbibutils"))
all.equal(names(bemore), c("Rcore", "Rpackage:rbibutils"))
## a large example with several files - needs internet access;
## it is better to clone repository https://github.com/iridia-ulb/references
## and work on local files
##
## iridia_mac <- c("abbrev.bib", "authors.bib", "journals.bib", "crossref.bib")
## iridia_biblio <- "biblio.bib"
##
## iridia_raw_url <- "https://raw.githubusercontent.com/iridia-ulb/references/master"
## iridia_mac_url <- file.path(iridia_raw_url, iridia_mac)
## iridia_biblio_url <- file.path(iridia_raw_url, iridia_biblio)
##
## bibdir <- tempdir()
## iridia_mac_loc <- file.path(bibdir, iridia_mac)
## iridia_biblio_loc <- file.path(bibdir, iridia_biblio)
##
## ## download the files to bibdir
## sapply(c(iridia_biblio_url, iridia_mac_url),
## function(x) download.file(x, file.path(bibdir, basename(x))))
##
## iridia <- readBib(iridia_biblio_loc, direct = TRUE, macros = iridia_mac_loc)
## iridia[1]
## print(iridia[1], style = "R")
## toBibtex(iridia[1]) # or: print(iridia[1], style = "bibtex")
## length(iridia) # 2576 at the time of writing
unlink(fn)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory (show via RShowDoc("KEYWORDS")):
% \keyword{ ~kwd1 }
% Use only one keyword per line.
% For non-standard keywords, use \concept instead of \keyword:
\concept{bibtex}
% Use only one concept per line.
rbibutils/man/rbibutils-package.Rd 0000644 0001762 0000144 00000020232 14047477144 016716 0 ustar ligges users \name{rbibutils-package}
\alias{rbibutils-package}
\alias{rbibutils}
\docType{package}
\title{
\packageTitle{rbibutils}
}
\description{
\packageDescription{rbibutils}
}
\details{
Package \pkg{rbibutils} provides an \R port of the \code{bibutils}
programs plus additional facilities. The main function,
\code{bibConvert}, offers all conversions between bibliography formats
supported by library \code{bibutils}. In addition, package
\pkg{rbibutils} converts to and from \R's \code{bibentry} Bibtex-based
bibliography format.
The core functionality is provided by the \code{bibutils} programs
which convert between various bibliography formats using a common MODS
XML intermediate format, see the source cited below.
Currently we provide the function \code{\link{bibConvert}}
for conversion between supported bibliography formats. For complete
list of formats supported by the package, see the documentation of
the original bibutils library.
\code{\link{readBib}} and \code{\link{writeBib}} import/export BiBTeX
files. \code{\link{readBibentry}} and \code{\link{writeBibentry}}
import/export \R source files in which the references are represented
by \code{bibentry()} calls. These functions were originally just
wrappers around \code{bibConvert}. \code{\link{readBib}} has acquired
additional features, including a direct import (without going through
\code{bibConvert}) from BiBTeX files.
All encodings supported by the bibutils library are available for
\code{\link{bibConvert}}.
Further functionality may be provided in future releases, in
particular, the underlying C functions could be exposed to package
authors. Further R wrappers may be added, as well. However, the scope
of the package will remain conversion between formats based on
\verb{bibutils} and manipulation of the MODS XML intermediate
format. \pkg{rbibutils} can be used also as an alternative to package
\pkg{bibtex} (Francois 2020). For bibliography management see package
\pkg{RefManager} (McLean 2017). For citations in R documentation (Rd
or roxygen2) see package \pkg{Rdpack} (Boshnakov 2020).
%
% The only external dependency is package \pkg{xml2}.
%
% Up to version 1.4 of \pkg{rbibutils} conversion to \code{"bibentry"}
% was done in \R using package \pkg{xml2}. From version 1.4.1 this
% conversion is done in the C code, just as all other conversions, so
% \pkg{xml2} is no longer needed.
% The legacy R code is still available and conversion between formats
% not involving bibentry do not need it. (import) so it could be made
% \dQuote{suggested} if there is a strong use case for that.
%
}
\section{Supported input and output formats}{
Most formats are supported for both input and output, see the listings
below. A format supported for input can be converted to any of the
output formats.
The input is first converted to \emph{MODS XML intermediate}, the
latter is then converted to the requested output format.
In \pkg{rbibutils} there are currently two exceptions to this rule.
First, the conversion from bibtex to bibentry offers the option to
bypass the conversion to \emph{MODS XML intermediate} and parse
directly the bibtex file, see \code{\link{readBib}} for details.
Second, the conversion from \verb{bibentry} to \verb{BibTeX} just uses
a \verb{print} method provided by \R.
In the table below column Abbreviation shows the abbreviation for
arguments \code{informat} and \code{outformat}, column FileExt gives
the default file extension for that format, column Input (Output)
contains TRUE if the format is supported for input (output) and FALSE
otherwise. Column Description gives basic description of the format.
\Sexpr[stage=build,results=rd]{paste("\\\\tabular{lllll}{", paste0(paste("\\\\strong{", colnames(rbibutils::rbibutils_formats), "}", collapse = " \\\\tab ")), "\\\\cr ", paste(rbibutils::rbibutils_formats[ , 1], rbibutils::rbibutils_formats[ , 2], rbibutils::rbibutils_formats[ , 3], rbibutils::rbibutils_formats[ , 4], rbibutils::rbibutils_formats[ , 5], sep = " \\\\tab ", collapse = "\\\\cr "), "\n}")}
\verb{bibentry} is the native \R variant of BibTeX. It can be input
directly from an \R source file or from a binary \verb{rds} file. The
\verb{"rds"} format is a compressed binary format. The \verb{rds} file
should contain a \verb{bibentry} R object, saved from R with
\code{saveRDS}. An R source file should contain one or more bibentry
instructions, see \code{\link{readBibentry}} for details of the
contents.
A \verb{bibentry} object can be written to a file as a binary
(\verb{"rds"}) object or as an \R source file, see
\code{\link{bibConvert}} and \code{\link{writeBib}} for details.
ADS is the reference format of the Smithsonian Astrophysical
Observatory (SAO) and National Aeronautics and Space Administration
(NASA) Astrophyics Data System.
For COPAC, see \verb{https://en.wikipedia.org/wiki/Copac}.
}
\author{Georgi N. Boshnakov (R code and R port of bibutils),
Chris Putnam (author of bibutils library)
}
% Maintainer: Georgi N. Boshnakov
\note{
The \code{bibutils} library is included in a number of software
packages. These include include pandoc and a library for
Haskell. Executable programs for conversion are available for Linux
distributions but seem not easily available for Windows. Executable
and libraries can also be generated out-of-the-box from the
\code{bibutils} disribution (on Windows under MSYS).
\pkg{rbibutils} adds conversions to/from \R's bibentry format and
direct conversion from bibtex, which preserves non-standard fields from
the bibtex source. There is also improved support for mathematical
expressions in bibtex files.
}
\references{
% bibentry:all
Georgi
N Boshnakov (2020).
\dQuote{Rdpack: Update and Manipulate Rd Documentation Objects.}
\doi{10.5281/zenodo.3925612}, R package version 2.0.0.
Damiano Fantini (2019).
\dQuote{easyPubMed: Search and Retrieve Scientific Publication Records from PubMed.}
R package version 2.13, \url{https://CRAN.R-project.org/package=easyPubMed}.
Romain Francois (2014).
\emph{bibtex: bibtex parser}.
R package version 0.4.0.
Mathew
William McLean (2017).
\dQuote{RefManageR: Import and Manage BibTeX and BibLaTeX References in R.}
\emph{The Journal of Open Source Software}.
\doi{10.21105/joss.00338}.
Chris Putnam (2020).
\dQuote{Library bibutils, version 6.10.}
\url{https://sourceforge.net/projects/bibutils/}.
% end:bibentry:all
}
\keyword{ package }
\seealso{
\code{\link{bibConvert} for further details and examples}
}
%\examples{
%}
% documentation for individual functions at
% https://sourceforge.net/p/bibutils/home/Bibutils/
%
% bib2xml convert BibTeX to MODS XML intermediate
% biblatex2xml convert BibLaTeX to MODS XML intermediate
% bibdiff compare two bibliographies after reading into the bibutils internal format
% copac2xml convert COPAC format references to MODS XML intermediate
% end2xml convert EndNote (Refer format) to MODS XML intermediate
% endx2xml convert EndNote XML to MODS XML intermediate
% isi2xml convert ISI web of science to MODS XML intermediate
% med2xml convert Pubmed XML references to MODS XML intermediate
% modsclean a MODS to MODS converter for testing puposes mostly
% nbib2xml convert Pubmed/National Library of Medicine nbib format
% to MODS XML intermedidate
% ris2xml convert RIS format to MODS XML intermediate
% xml2ads convert MODS XML intermediate
% into Smithsonian Astrophysical Observatory
% (SAO)/National Aeronautics and Space Administration (NASA)
% Astrophyics Data System
% or ADS reference format (converter submitted by Richard Mathar)
% xml2bib convert MODS XML intermediate into BibTeX
% xml2biblatex convert MODS XML intermediate into BibLaTeX
% xml2end convert MODS XML intermediate into format for EndNote
% xml2isi convert MODS XML intermediate to ISI format
% xml2nbib convert MODS XML intermediate
% to Pubmed/National Library of Medicine nbib format
% xml2ris convert MODS XML intermediate into RIS format
% xml2wordbib convert MODS XML intermediate into Word 2007 bibliography format
rbibutils/man/readBibentry.Rd 0000644 0001762 0000144 00000005316 14160045550 015732 0 ustar ligges users \name{readBibentry}
\alias{readBibentry}
\alias{writeBibentry}
\title{Read and write bibentry files}
\description{Read and write bibentry files.}
\usage{
readBibentry(file, extra = FALSE, fbibentry = NULL)
writeBibentry(be, file, style = c("Rstyle", "loose"))
}
\arguments{
\item{be}{a bibentry object.}
\item{file}{filename, a character string.}
\item{extra}{if \code{TRUE} allow non-standard bibtex types.}
\item{style}{
if \code{"Rstyle"} (default), wrap in \code{c()}, otherwise don't
wrap and don't put commas between the entries, see Details section.
}
\item{
fbibentry}{a function to use for generating bib objects instead
of \code{bibentry()}.
}
}
\details{
These functions read/write \code{bibentry} objects from/to R source
files. Two styles are supported. \code{"Rstyle"} is the format used by
\code{print(be, style = "R")}, which writes the \code{bibentry} calls
as a comma separated sequence wrapped in \code{c()}. Style
\code{"loose"} writes the entries without separators and no wrapping.
\code{writeBibentry} writes the object to the specified file in the
requested style (default is \code{"Rstyle"}).
\code{readBibentry} reads the file and creates a \code{bibentry}
object. It doesn't have argument for style, since that is inferred
from the contents of the file.
\code{bibentry()} calls that throw errors are not included in the
returned object. The errors are intercepted and converted to warnings,
identifying the corresponding \code{bibentry()} calls by their keys,
if present (otherwise the text of the whole bibentry is shown).
}
\value{
for \code{writeBibentry}, \code{NULL} (invisibly)
for \code{readBibentry}, a \code{bibentry} object with the keys as
names
}
%\references{
%%% ~put references to the literature/web site here ~
%}
\author{Georgi n. Boshnakov}
%\note{
%%% ~~further notes~~
%}
%
%%% ~Make other sections like Warning with \section{Warning }{....} ~
%
\seealso{
\code{\link{readBib}} and \code{\link{writeBib}} for reading/writing
bib files,
\code{\link{bibConvert}}
}
\examples{
bibs <- readBib(system.file("REFERENCES.bib", package = "rbibutils"),
encoding = "UTF-8")
fn <- tempfile(fileext = ".bib")
writeBibentry(bibs, file = fn) # style = "Rstyle" (default)
cat(readLines(fn), sep = "\n")
writeBibentry(bibs, file = fn, style = "loose")
cat(readLines(fn), sep = "\n")
unlink(fn)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory (show via RShowDoc("KEYWORDS")):
% \keyword{ ~kwd1 }
% \keyword{ ~kwd2 }
% Use only one keyword per line.
% For non-standard keywords, use \concept instead of \keyword:
% \concept{ ~cpt1 }
% \concept{ ~cpt2 }
% Use only one concept per line.
rbibutils/man/rbibutils_formats.Rd 0000644 0001762 0000144 00000002415 14047475271 017062 0 ustar ligges users \name{rbibutils_formats}
\alias{rbibutils_formats}
\docType{data}
\title{Supported bibliography formats}
\description{Supported bibliography formats in package rbibutils.}
\usage{rbibutils_formats}
\format{
A data frame with 16 observations on the following 5 variables.
\describe{
\item{\code{Abbreviation}}{a character vector.}
\item{\code{FileExt}}{a character vector.}
\item{\code{Input}}{a logical vector.}
\item{\code{Output}}{a logical vector.}
\item{\code{Description}}{a character vector.}
}
}
\details{
Each row in \code{rbibutils_formats} gives information about a supported
bibliography formats in package \pkg{rbibutils}.
\code{Abbreviation} is the name to use in arguments \code{informat}
and \code{outformat} in \code{\link{bibConvert}}.
\code{FileExt} is the default extension used to infer the input/output
format if the corresponding argument is missing.
\code{Input} (\code{Output}) is \code{TRUE} if the format is supported
for input (output).
\code{Description} gives a brief description of the format.
}
% \source{
% %% ~~ reference to a publication or URL from which the data were obtained ~~
% }
% \references{
% %% ~~ possibly secondary sources and usages ~~
% }
\examples{
rbibutils_formats
}
\keyword{datasets}
rbibutils/TODO 0000644 0001762 0000144 00000001323 14225116626 012745 0 ustar ligges users - 2022-04-11
Investigate why the examples with pubmed are so slow, see the comment in one of the commits
on 2022-04-11.
- 2020-09-27
In bibtex import, mathematical formulas are exported without the enclosing dollars for
entries coming before field AUTHORS. If field AUTHORS is the first in a reference item
there is no problem.
bibacc2 <- system.file("/bib/latin1accents_utf8a.bib", package = "rbibutils")
be0a <- readBib(bibacc2)
## Error in .bibentry_check_bibentry1(rval) :
## A bibentry of bibtype ‘Article’ has to specify the field: author
## Warning message:
## In readBibentry(outfile) : key 'test1'
## A bibentry of bibtype ‘Article’ has to specify the field: author
rbibutils/DESCRIPTION 0000644 0001762 0000144 00000004114 14516216412 013761 0 ustar ligges users Package: rbibutils
Type: Package
Title: Read 'Bibtex' Files and Convert Between Bibliography Formats
Version: 2.2.16
Authors@R: c( person(given = c("Georgi", "N."), family = "Boshnakov",
role = c("aut", "cre"),
email = "georgi.boshnakov@manchester.ac.uk",
comment = "R port, R code, new C code and modifications to bibutils' C code, conversion to Bibentry (R and C code)"
),
person(given = "Chris", family = "Putman",
role = "aut",
comment = "src/*, author of the bibutils libraries, https://sourceforge.net/projects/bibutils/"),
person(given = "Richard", family = "Mathar",
role = "ctb",
comment = "src/addsout.c"),
person(given = "Johannes", family = "Wilm",
role = "ctb",
comment = "src/biblatexin.c, src/bltypes.c")
)
Description: Read and write 'Bibtex' files. Convert between bibliography
formats, including 'Bibtex', 'Biblatex', 'PubMed', 'Endnote', and
'Bibentry'. Includes a port of the 'bibutils' utilities by Chris
Putnam . Supports all
bibliography formats and character encodings implemented in
'bibutils'.
License: GPL-2
URL: https://geobosh.github.io/rbibutils/ (doc),
https://github.com/GeoBosh/rbibutils (devel)
BugReports: https://github.com/GeoBosh/rbibutils/issues
Depends: R (>= 2.10)
Imports: utils, tools
Suggests: testthat
Encoding: UTF-8
NeedsCompilation: yes
Config/Needs/memcheck: devtools, rcmdcheck
Packaged: 2023-10-25 13:16:13 UTC; georgi
Author: Georgi N. Boshnakov [aut, cre] (R port, R code, new C code and
modifications to bibutils' C code, conversion to Bibentry (R and C
code)),
Chris Putman [aut] (src/*, author of the bibutils libraries,
https://sourceforge.net/projects/bibutils/),
Richard Mathar [ctb] (src/addsout.c),
Johannes Wilm [ctb] (src/biblatexin.c, src/bltypes.c)
Maintainer: Georgi N. Boshnakov
Repository: CRAN
Date/Publication: 2023-10-25 13:50:02 UTC
rbibutils/build/ 0000755 0001762 0000144 00000000000 14516212435 013353 5 ustar ligges users rbibutils/build/partial.rdb 0000644 0001762 0000144 00000056723 14516212435 015515 0 ustar ligges users xYv`&afx H9A3ٙ݅vT. 5ꩪ&UdYeI+i6(8+8h%˖____Nz~~OWF[Ԝ?@{ι瞛?ڙd:2[;d::<(~t-ܚsYpKOl/dvHlXKٻo^γ9=S%j)?kxsk顫
K97
宒U1U5Aw?bK>%isˏ#*{f>ďA6;H$[h{jc%zv8(g/\\zB)G]pa̾xͲ=) 0n6HqT/іƷâчnp9PCz/˶[vȱGbO1^V"c H=Mn
YA 2 [.1n.yVyy-^
|E;a$4XfF"=xKWjYJ'mt cgVx͜sK6sYl3R.^`#d9&
@.cJ%AAfls^>D鲪"Gvx^;:nД<8n).nNHg#Dɩ&A"ģZi[ BM*.phb=fb4K2jdtE S' tx}m?W0@Y0!ЇZj=| j1]qJcrEej2\w[
:QTN\ X-[<+<^ = =lzu4ö8z$EG%ē;Pwގ4p@ɷ
35&NdR5'&=C;$ēCKR;0t@ɻzv]E|F]h,5|wuTӶ$6X~ p.ꁫ* =]d\p^RPP>ͲXE0
Z?_c tG=M۶I;ؼPǁ4K0aSOjQ<
tk`5䈝`Y{nV na]+lwWGp
VۇahZ.ARA
ؖ"苛&ynAO~!L&
\ݠ[p{&aY&ņ [p^`+)6s;
7*ac1]+pwf1$P7pDy&QrV|>^{J
Wc7ki##휳䢙0CcX=Y멺q5艍wpkIГ8O.~n}bC]\Z̩,]7pFw tN"43EI^5 f]cq,nBD<dYK캀o(R̂q;4FU}=
=-w/TT,ۋV [-,r5xa/^c,^U5f x_#vàmUp0#۠oEyAbbr'ضEJتIh^0c& oյ#!MMQ.ZN PYZ:yfZAz[(&V$K aXmOjhȩ:q7(ULr9oyK]jt/}آa;:+pgxJfl<(HA(5ihMNlIFS7>$v{'@жOU ͌慳Z,ptt\2#G-sE'j&F3;;RVJ[fb: xtf5!vcu
玔J٢ERi?
/LlU=d=Z4jJknwv
˫H]QJჄӠ2}w~8H%lhR VI~U|Z4 I G@E]V
_(&5𦾅ZvL0r!BsY짢pfjx9e½U^Zsp, Љ&f7[1IQqq4Z{f$ `/ލ04h2C
`?M<+cUW-3Cje&o-t|5UZ./?1 .:!ZlZU V|=1Nr%J2Fl
4
gA=bmux).1=>V&q9h'JVC
4
Ƈbwxt4N{`|j&Yng@A\P?
kPVQcg,W+^}\w8-_R.$N@+)7~ZBS,FI;$Lf-$Yy\>=