readBib {rbibutils}

Read and write bibtex files

Description

Read and write bibtex files.

Usage

readBib(file, encoding = NULL, ..., direct = FALSE, 
        texChars = c("keep", "convert", "export", "Rdpack"), 
        macros = NULL, extra = FALSE, key, fbibentry = NULL)

writeBib(object, con = stdout(), append = FALSE)

charToBib(text, informat, ...)

Arguments

file

name or path to the file, a character string.

encoding

the encoding of file, a character string.

direct

If TRUE parse 'file' directly to bibentry, otherwise convert first to intermediate XML, then to bibentry.

texChars

What to do with characters represented by TeX commands (for example, accented Latin charaters? If "export", export as TeX escapes when possible. If "convert", convert to the target encoding. If "keep", output the characters as they were in the input file, like "export", but don't convert normal characters to TeX escapes.

"Rdpack" is mainly for internal use and its actions may be changed. It is equivalent to "keep" plus some additional processing, see https://github.com/GeoBosh/rbibutils/issues/7#issue-1020385889.

macros

additional bib files, usually containing bibtex macros, such as journal abbreviations.

object

a bibentry object.

con

filename (a character string) or a text connection

append

if TRUE append to the file.

text

a character vector.

informat

the input format, defaults to "bibtex".

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.

...

for charTobib, arguments to be passed on to readBib or bibConvert, see Details. Not used by readBib and writeBib (which throw error to avoid silently ignoring unknown arguments).

extra

if TRUE, allow non-standard bibtex types.

fbibentry

a function to use for generating bib objects instead of bibentry(), see Details.

Details

readBib is wrapper around bibConvert for import of bibtex files into bibentry objects.

If 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 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 texChars, currently implemented only for the case direct = TRUE, gives some control over the processing of TeX sequences representing characters (such as accented Latin characters): If it is "keep" (the default), such sequences are kept as in the input. "convert" causes them to be converted to the characters they represent. Finally, "export" exports characters as TeX sequences, whenever possible.

The difference between "keep" and "export" is that "keep" does not convert normal characters to TeX escapes, while "export" does it if possible. For example, if the input file contains the TeX sequence ⁠\"o⁠ representing the letter o-umlaut, "keep" and "export" will keep it as TeX sequence, while "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 "keep" and "convert" will convert it to the output encoding of o-umlaut, while "export" will export it as ⁠\"o⁠.

Currently, texChars = "export" does not process properly mathematical formulas.

fbibentry, if supplied, should be a function with arguments like bibentry to be used instead of utils::bibentry for creating bib objects in R.

writeBib writes a bibentry object to a bibtex file.

charTobib is a convenience function for reading or converting bibliography information, accepting the input from a character vector rather than a file. If informat is missing it calls readBib, otherwise bibConvert. In both cases the remaining arguments are passed on and should be suitable for the called function.

The files specified by argument macros are read in before those in file. Currently this is implemented by concatenating the files in the order they appear in c(macros, file). It is ok for macros to be character(0).

Value

for readBib, a bibentry object. If extra is TRUE it can also be bibentryExtra (which inherits from bibentry). If fbibentry is a function the return value is whatever it returns.

for writeBib, the bibentry object (invisibly)

Author(s)

Georgi N. Boshnakov

See Also

readBibentry and writeBibentry for import/export to R code.

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)