The citeproc-lua is a Lua implementation of the Citation Style Language (CSL), an XML-based language that defines the formats of citations and bibliography. With a CSL processor (citeproc), references can be generated according to the rules specified in the style. This project aims to provide a replacement for BibTeX, the traditional bibliography processor used for LaTeX.

Some the interfaces and code design are borrowed from Juris-M/citeproc-js and brechtm/citeproc-py and thanks to both projects.

The citeproc-lua is written with Lua 5.3 but it has not been tested with other versions. It is built upon the following packages.

• slnunicode (Part of LuaTeX)
• michal-h21/LuaXML (CTAN)
• michal-h21/lua-uca (CTAN) (to be used)

These packages are available in the latest version of TeX Live. To correctly load the modules in a Lua script, you may state kpse.set_program_name("luatex") at the beginning of the file and run it with texlua program.

A simple example is in the example/ directory.

Note that the API is not stable and is likely to change in the future.

local citeproc = require("citeproc")
local engine = citeproc.new(sys, style)

The sys is a table which must contain retrieveLocale() and retrieveItem() functions. Thet are called to feed the engine with inputs.

The updateItems() method refreshes the registry of the engine.

params, result = engine:updateItems(ids)

The ids is just a list of ids.

ids = {"ITEM-1", "ITEM-2"}

The makeCitationCluster() method is called to generate a citation of (possibly) multiple items.

params, result = engine:makeCitationCluster(cite_items)

The cite_items is a list of tables which contain the id and other options (not implemented).

cite_items = {
  { id = "ITEM-1" },
  { id = "ITEM-2" }
}

Returns:

"(D’Arcus, 2005; Bennett, 2009)"

The more complicated method processCitationCluster() is not implemented yet.

The makeBibliography() method produces the bibliography and parameters required for formatting.

result = engine:makeBibliography()

Returns:

result = {
  {
    hangingindent = false,
    ["second-field-align"] = false,
  },
  {
    '<div class="csl-entry">B. D’Arcus, <i>Boundaries of Dissent: Protest and State Power in the Media Age</i>, Routledge, 2005.</div>',
    '<div class="csl-entry">F.G. Bennett Jr., “Getting Property Right: ‘Informal’ Mortgages in the Japanese Courts,” <i>Pac. Rim L. &#38; Pol’y J.</i>, vol. 18, Aug. 2009, pp. 463–509.</div>'
  }
}

The busted library is required to run the tests. Make sure it is installed with the same Lua version as LuaTeX so that it can be loaded correctly.

luarocks --lua-dir /usr/local/opt/[email protected] --lua-version 5.3 install busted

Clone the two submodules test-suite and locales into the test/ directory.

git submodule update --init

Run all the tests from test-suite.

busted --run=citeproc

The log is printed to test/citeproc-test.log. Currently the citeproc-lua has passed 594 of 853 tests from test-suite.

Select tests via pattern.

busted --run=citeproc --filter=sort_CitationNumber

Run the test of modules in citeproc-lua.

busted --pattern=formatted_text --filter=quotes

• CSL
  • CSL Homepage
  • CSL 1.0.1 specification
  • CSL 1.0.2 specification
  • CSL 1.1 specification
  • CSL schema
  • CSL processors in other languages
    • Juris-M/citeproc-js
      • documentation
    • brechtm/citeproc-py
    • jgm/citeproc
    • andras-simonyi/citeproc-el
    • inukshuk/citeproc-ruby
    • zotero/citeproc-rs
  • CSL locales
  • CSL styles
  • CSL test-suite
• Articles
  • A Citation Style Language (CSL) workshop (TUGboat article)
• Discussions
  • Citation Style Language vs. biblatex