R: Read and write bibtex files

readBib {rbibutils} | R Documentation

## Read and write bibtex files

### Description

Read and write bibtex files.

### Usage

    readBib(file, encoding = NULL, ..., direct = FALSE,
            texChars = c("keep", "convert", "export"))

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

### 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.
`object` | a `bibentry` object.
`con` | filename (a character string) or a text connection
`append` | if `TRUE` append to the file.
`...` | Not used and throws error to avoid silently ignoring unknown arguments.

### 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`.

Note that `"convert"` converts also a large number of mathematical symbols (such as `"\alpha"`) to the target encoding (UTF-8), which may or may not be desirable. Also, some mathematical formulas may cause surprises.

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

`writeBib` writes a `bibentry` object to a bibtex file.

### Value

for `readBib`, a `bibentry` object

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)

    ## 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")

    ## "convert" converts to characters
    ## a lot of TeX commands representing symbols
    be3 <- readBib(bibacc, direct = TRUE, texChars = "convert")
    ## be3
    print(be3, style = "R")
    ## print(be3, style = "bibtex")

    unlink(fn)

[Package rbibutils version 2.1.1 Index]