Handle bibliography or citation text

Description

These functions define what happens to the text retrieved from Zotero:

Usage

zt_return(text)

zt_print(text)

zt_insert(text)

zt_copy(text)

Arguments

Details

• zt_return() returns the text invisibly (useful in scripts).

• zt_print() writes the text to the console via cat().

• zt_insert() inserts the text at the cursor position in RStudio, falling back to zt_print() when RStudio is not available.

• zt_copy() copies the text to the system clipboard.

Value

All functions return text invisibly.

Examples

zt_print("[@doe2020]")
zt_return("[@doe2020]")

Fetch bibliography data for specific citation keys

Description

Returns bibliography data for a vector of Better BibTeX citation keys.

Usage

zt_bib(
  keys,
  format = getOption("zoter.default.format", "biblatex"),
  library_id = getOption("zoter.default.library_id", 1L),
  .action = zt_return
)

Arguments

Value

Bibliography text, returned according to .action.

Recommended format

Use "json" (CSL-JSON) unless you are using a raw TeX citation engine. R Markdown converts other formats to CSL-JSON, and the conversion is lossy for non-article reference types.

Examples

## Not run: 
zt_bib(c("doe2020", "smith2019"), format = "json")

## End(Not run)

Fetch a bibliography via cite-as-you-write

Description

Opens the Better BibTeX CAYW picker in Zotero and returns bibliography data for the chosen items in the requested format.

Usage

zt_bib_cayw(
  format = getOption("zoter.default.format", "biblatex"),
  .action = zt_return
)

Arguments

Value

Bibliography text, returned according to .action.

Examples

## Not run: 
zt_bib_cayw(format = "json", .action = zt_print)

## End(Not run)

Extract the bibliography file path from a document's YAML front matter

Description

Reads the YAML front matter of an R Markdown or Quarto document and returns the value of the bibliography field. Relative paths are resolved relative to the document's directory.

Usage

zt_bib_path(path_doc, encoding = "UTF-8")

Arguments

Value

An absolute path to the bibliography file.

Fetch bibliography for currently selected Zotero items

Description

Returns bibliography data for the items currently highlighted in the Zotero window.

Usage

zt_bib_selected(
  format = getOption("zoter.default.format", "biblatex"),
  .action = zt_return
)

Arguments

Value

Bibliography text, returned according to .action.

Examples

## Not run: 
zt_bib_selected(format = "json", .action = zt_print)

## End(Not run)

Insert a Zotero citation using cite-as-you-write

Description

Opens the Better BibTeX cite-as-you-write (CAYW) picker in Zotero and returns or inserts the formatted citation.

Usage

zt_cite(format = c("pandoc", "latex", "cite"), .action = zt_return)

Arguments

Value

The citation string, returned according to .action.

Examples

## Not run: 
# Returns citation string
zt_cite(format = "pandoc", .action = zt_return)

## End(Not run)

Detect pandoc-style citation keys in a document

Description

Scans one or more files for pandoc-style citation keys (⁠@key⁠) and returns a character vector of unique keys found. Text inside code chunks, inline R expressions, and URLs is intentionally excluded to avoid false positives.

Usage

zt_detect_citations(path = zt_knitr_input())

zt_detect_citations_text(text)

Arguments

Details

To force a key to appear in the output (e.g. for a reference you mention only in a caption), add it to an HTML comment or to the nocite front matter field.

Value

A character vector of unique citation keys (without the leading @).

Examples

tmp <- tempfile(fileext = ".Rmd")
writeLines(c(
  "See [@doe2020] and @smith2019.",
  "Not this one: \\@escaped or `r '@inline'`"
), tmp)
zt_detect_citations(tmp)
unlink(tmp)
zt_detect_citations_text("See [@doe2020] and @smith2019.")

Low-level HTTP helpers for the Better BibTeX API

Description

zt_get() sends a GET request to a Better BibTeX endpoint and returns the response body as a character string. zt_json_rpc() sends a JSON-RPC 2.0 POST request and returns the parsed response list.

Usage

zt_get(endpoint, ...)

zt_json_rpc(method, params = list())

Arguments

Value

zt_get() returns a character string. zt_json_rpc() returns a list with elements result (on success) or error (on failure).

Guess the citation format from a file path

Description

Returns "latex" for .tex files and "pandoc" for everything else.

Usage

zt_guess_citation_format(path)

Arguments

Value

A character string, either "pandoc" or "latex".

Examples

zt_guess_citation_format("paper.Rmd")
zt_guess_citation_format("paper.tex")

Guess the bibliography file format from a file path

Description

Inspects the file extension of path and returns the corresponding Better BibTeX translator name.

Usage

zt_guess_format(path, dot_bib = getOption("zoter.default.bib", "biblatex"))

Arguments

Value

A character string: one of "json", "biblatex", "bibtex", or "yaml".

Examples

zt_guess_format("refs.json")
zt_guess_format("refs.bib")
zt_guess_format("refs.yaml")

Check whether the Better BibTeX HTTP endpoint is reachable

Description

zt_is_running() returns TRUE if Zotero is open and the Better BibTeX add-on is active, FALSE otherwise. zt_assert_running() throws an informative error if it is not.

Usage

zt_is_running()

zt_assert_running()

Value

zt_is_running() returns a single logical value. zt_assert_running() is called for its side-effect and returns NULL invisibly.

Examples

zt_is_running()

Return the current knitr input file

Description

A thin wrapper around knitr::current_input() that throws an informative error when called outside a knitr session.

Usage

zt_knitr_input()

Value

The path to the current knitr input file.

List available Zotero libraries

Description

Returns a data frame with the id and name of all Zotero libraries (personal library and any group libraries) accessible through Better BibTeX.

Usage

zt_libraries()

Value

A data frame with columns id (integer) and name (character).

Examples

## Not run: 
zt_libraries()

## End(Not run)

Look up a Zotero library ID by name

Description

Convenience wrapper around zt_libraries() that returns the integer ID for a named library. Useful when you need to pass library_id to zt_bib() or zt_write_bib() in a way that is portable across machines (where numeric IDs may differ).

Usage

zt_library_id(name)

Arguments

Value

An integer vector of library IDs, the same length as name. Returns NA_integer_ for NA inputs.

Examples

## Not run: 
zt_library_id("My Library")

## End(Not run)

Update a bibliography file from an R Markdown / Quarto document

Description

Detects citation keys in path_doc, then calls zt_write_bib() to refresh the bibliography file declared in the document's YAML front matter (or path_bib if supplied explicitly).

Usage

zt_update_bib(
  path_doc,
  path_bib = zt_bib_path(path_doc),
  ignore = character(),
  format = zt_guess_format(path_bib),
  library_id = getOption("zoter.default.library_id", 1L),
  overwrite = TRUE,
  filter = identity,
  quiet = FALSE
)

Arguments

Value

path_bib, invisibly.

Examples

## Not run: 
zt_update_bib("paper.Rmd")

## End(Not run)

Write a bibliography file from Zotero citation keys

Description

Fetches bibliography data for the given keys from Zotero and writes it to path. Intended for use in YAML front matter to keep bibliography files in sync automatically:

Usage

zt_write_bib(
  path,
  keys = zt_detect_citations(),
  ignore = character(),
  format = zt_guess_format(path),
  library_id = getOption("zoter.default.library_id", 1L),
  overwrite = FALSE,
  filter = identity
)

Arguments

Details

bibliography: "`r zoteR::zt_write_bib('refs.json', overwrite = TRUE)`"

Value

path, invisibly (for use in YAML front matter).

Examples

## Not run: 
zt_write_bib("refs.json", overwrite = TRUE)
zt_write_bib("refs.bib",  overwrite = TRUE)

## End(Not run)